home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / basic / RIBlitzLibs.lha / riblitzlibs / docs / RICopperFXLib.doc < prev    next >
Encoding:
Text File  |  1995-01-28  |  7.3 KB  |  196 lines
  1. -----------------------------------------------------------------------------
  2. ----                 RI CopperFX Library V1.3 (C)94/95                   ----
  3. -----------------------------------------------------------------------------
  4.  
  5.                         Written By Stephen McNamara
  6.                         ©94/95 Leading Edge Software
  7.  
  8.  
  9. This is a library of commands that assist in setting it custom copperlists
  10. for your blitz mode games.  It interfaces with the display library and so
  11. can only be used in conjunction with CopList objects.  The commands in this
  12. library insert copper instructions into the custom space in a Coplist
  13. object - you must therefore have custom space in your CopList if you want
  14. to use them.
  15. Custom space is given to the coplist object during initialisation - it is
  16. the last parameter of the InitCopList command.
  17.  
  18. AGA warning: Three of the commands in this library are AGA only
  19.              (A1200/A400/CD32).  They should not be used on non-AGA
  20.              machines.
  21.  
  22. Command list:
  23.  
  24.         CopperReset coplist#,startline[,ccoffset]
  25.         DoColSplit cols_adr,numlines,colour_register
  26.         RedoColSplit cols_adr,numlines,ccoffset
  27.         CopperEnd
  28.         CopperInfoBlock
  29.         CopperCommand copins1,copins2
  30.         CopperMove register,value
  31.         CopperWait x,y
  32.         CopperSkip x,y
  33.         GetCCOffset
  34.         CopperAGACol
  35.  
  36.  
  37. Statement: CopperReset
  38. ------------------------------------------------------------------------
  39. Modes : Amiga/Blitz
  40. Syntax: CopperReset coplist#,startline[,ccoffset]
  41.  
  42. This command sets up the copper library to work on a certain coplist
  43. object. It must be used before you can use any of the commands in this
  44. library.  coplist# is the number of the coplist you want to effect,
  45. startline is the vertical start position to store (for the commands
  46. DoColSplit and RedoColSplit).  The optional ccoffset parameter allows you
  47. to specify an offset into the custom area of the copperlist as a start
  48. position for the library.  The ccoffset parameter is given in the form of
  49. the number of copper instructions from the start of the custom area.
  50.  
  51.  
  52. Statement/Function: DoColSplit
  53. ------------------------------------------------------------------------
  54. Modes : Amiga/Blitz
  55. Syntax: DoColSplit cols_adr,numlines,colour_register
  56.  
  57.   This command is AGA only at the moment.  What it does is produce a nice
  58. aga fade going down the screen.  The colours to fade from/to are given in
  59. the form of 6 longwords, the address of which is pointed to by cols_adr.
  60. The following structure could be used to store the colours:
  61.  
  62.         Newtype.colourinfo
  63.             r1.l
  64.             g1.l
  65.             b1.l
  66.             r2.l
  67.             g2.l
  68.             b2.l
  69.         End Newtype
  70.  
  71. You would then assign a variable to be of type .colourinfo, and set the
  72. colour values in it.  It would then be passed to the DoColSplit command
  73. using the & operator to pass the address of the variable:
  74.  
  75.         Deftype.colourinfo cols
  76.         cols\r1=0,0,0,255,255,255
  77.         DoColSplit &cols,256,0
  78.  
  79. The split will start at the current y counter value (set by CopperReset)
  80. and will go on for numlines vertical lines.  It will effect the colour
  81. register supplied, which maybe any aga register.  The Y counter will be
  82. moved down to the end of the colour split after this command has finished,
  83. meaning that you can do multiple splits one after the other easily.
  84.  
  85.  
  86. Statement/Function: RedoColSplit
  87. ------------------------------------------------------------------------
  88. Modes : Amiga/Blitz
  89. Syntax: RedoColSplit cols_adr,numlines,cc_offset
  90.  
  91. This command must be used after the DoColSplit.  What it allows you to do
  92. is quickly update the colour information set up by the DoColSplit command
  93. without rebuilding the whole colour split.  The parameters are the same
  94. except that cc_offset replaces the colour register parameter.  For this
  95. command to work, you must start it at the same custom address as the
  96. DoColSplit was started at.  This parameter is for you to pass the address
  97. to start at too the library.  An easy way to do this is to store the
  98. current cc_offset BEFORE calling DoColSplit:
  99.  
  100.         pos.w=GetCCOffset
  101.         DoColSplit &cols,256,0
  102.         ;
  103.         ; Change colours values in cols variable here!
  104.         ;
  105.         RedoColSplit &cols,256,pos
  106.  
  107.  
  108. Statement/Function: CopperEnd
  109. ------------------------------------------------------------------------
  110. Modes : Amiga/Blitz
  111. Syntax: CopperEnd
  112.  
  113. This command is used to tidy up the copperlist after you have finished
  114. adding custom commands.  It is necessary if you're ever executing any WAIT
  115. commands (including DoColSplit) after vertical position 255.  After this
  116. position extra code is required to make sure the CopList display terminated
  117. properly.  If you don't use it after going over 255 vertically, you will
  118. get screen corruption in your display.
  119.  
  120.  
  121. Statement/Function: CopperInfoBlock
  122. ------------------------------------------------------------------------
  123. Modes : Amiga/Blitz
  124. Syntax: ad.l=CopperInfoBlock
  125.  
  126. Returns the address of the internal library information.  This command is
  127. primarily for debugging by me.  The data held within the structure is
  128. private, and no assumptions should be made about it by the user of this
  129. library.
  130.  
  131.  
  132. Statement: CopperCommand
  133. ------------------------------------------------------------------------
  134. Modes : Amiga/Blitz
  135. Syntax: CopperCommand copins1,copins2
  136.  
  137. This command allows you to manually insert copper instructions into the
  138. current set coplist object.  The copper instruction is given as two words
  139. which are stored straight into the coplist.
  140.  
  141.  
  142. Statement: CopperMove
  143. ------------------------------------------------------------------------
  144. Modes : Amiga/Blitz
  145. Syntax: CopperMove register,value
  146.  
  147. This command allows you to insert a move instruction into the copperlist.
  148. The first parameter should be a hardware register address (given as an
  149. offset from $0), the second should be a value to move into it.  The value
  150. parameter must be a word.
  151.  
  152.  
  153. Statement: CopperWait
  154. ------------------------------------------------------------------------
  155. Modes : Amiga/Blitz
  156. Syntax: CopperWait x,y
  157.  
  158. This command allows you to insert a wait instructino into the copperlist.
  159. The horizontal and vertical position to wait for are given by x,y.  The
  160. copper has a horizontal resolution though of 4 low resolution pixels,
  161. thus your x coordinate will be rounded down to the nearest multiple of 4.
  162.  
  163.  
  164. Statement: CopperSkip
  165. ------------------------------------------------------------------------
  166. Modes : Amiga/Blitz
  167. Syntax: CopperSkip x,y
  168.  
  169. This command allows you to insert a wait instructino into the copperlist.
  170. The horizontal and vertical position to wait for are given by x,y.  The
  171. copper has a horizontal resolution though of 4 low resolution pixels,
  172. thus your x coordinate will be rounded down to the nearest multiple of 4.
  173.  
  174.  
  175. Function: GetCCOffset
  176. ------------------------------------------------------------------------
  177. Modes : Amiga/Blitz
  178. Syntax: offset=GetCCOffset
  179.  
  180. Gets the current custom copper instruction offset.  Used if you want to
  181. keep track of how far through your custom area you are, or in conjunction
  182. with Do/RedoColSplit.  The return value is the number of instructions from
  183. the start of the custom area.
  184.  
  185.  
  186. Statement: CopperAGACol
  187. ------------------------------------------------------------------------
  188. Modes : Amiga/Blitz
  189. Syntax: CopperAGACol register,r,g,b
  190.  
  191. Setting AGA colours is a pain in the arse.  This instruction though allows
  192. you to do it easily in your copperlist by doing all the extra work for you.
  193. Just supply the colour register number to move the data into and the r,g,b
  194. values.  This command generates 4 copper instructions inside your
  195. copperlist.
  196.